/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package com.sun.dtv.resources;

/**
 *
 * @author stupied
 */
public interface ScarceResource {



    /**
     * Requests reservation of the given scarce resource instance.
     * 
     * @param force If true, this method will withdraw the resource from the current owner. If false, the implementation will block and wait until the resource is made available (using release()) or until timeoutms.
     * @param timeoutms A positive amount of time in millisecond until which this method will wait for the resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.
     * @param listenerThe listener to be attached to receive notification about the status of the resource.

     * @throws java.lang.IllegalArgumentException If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.
     * @throws com.sun.dtv.resources.TimeoutException If the time specified in timeoutms is over and the resource could not be reserved.
     * @throws java.lang.SecurityException If the application has no permission for the reserve action for the resource it is about to reserve. Also thrown if force is set to true  but the application has no permission for the force action.
     */
    void reserve(boolean force, long timeoutms, ScarceResourceListener listener)
             throws IllegalArgumentException, TimeoutException, SecurityException;

    /**
     * Releases this resource.
     */
    void release();

    /**
     * Checks whether the given resource is currently available for reservation.
     * @return A boolean set to true if the given resource is currently available for reservation.
     */
    boolean isAvailable();
}
